netvendfandomcom-20200214-history
Using the netvend api
This article assumes the use of the Python api. First you'll need to download the api. You can find the latest version here. At the moment this only works with Python 2.x. If you'd like to follow along or play around with netvend yourself, the seed used in these examples should already have credit on it. It's meant to be used by anyone, and feel free to tip some of the credit away to your own agent. Or, you can manually deposit Bitcoin, which I've written about here. With that out of the way, let's jump right in: import netvend #set up an agent, using the seed "correct horse battery staple" #the seed is used to generate a Bitcoin keypair for the agent #this will be used to authenticate requests to the server #without seed=True, the constructor can use a private key directly. agent = netvend.Agent("correct horse battery staple", seed=True) #print the bitcoin address associated with this private key. #As with Bitcoin itself, this address is all someone needs to send you tips. print agent.get_address() #until this point, no connection has been made. #the first thing we'll do is print out the netvend balance for the agent #this is nothing more than a convenience function that sends a specific query command balance_usats = agent.fetch_balance() #this will be in microSatoshis, #so we can use a netvend function to express it in more familiar units print "balance (in btc):", netvend.convert_value(balance_usats, "usats", "btc") #generates a post command with the text "test!!", #signs the command, and sends it to the netvend server. response = agent.post("test!!") This is all the code you need to begin interacting with netvend. The agent.fetch_balance and agent.post lines will block while the api waits for the server response. Alternatively, a callback function can be specified as an additional argument, for asynchronous use (this applies to all 4 commands). The data "test!!" will now be stored on netvend (assuming this agent has netvend credit). This is a public, transparent server. To store private data, the user or script can encrypt the data however they like. response now contains a dictionary that looks like this: {'success': 1, 'history_id': 3971, 'command_result': 28, 'charged': 3500} indicating: * the command was successful * this is event number 3971 in netvend's history * in post's case, command_result tells us the post_id of the new post (28, here) * the agent has been debited 3500 uSat, or 0.0035 satoshis, of netvend credit. If you try other private keys or seeds, they probably won't work right away, as they won't have credit. You can use another netvend command, tip, to send credit from your agent to other agents. We'll use this now to give a new agent some starting credit. (You can also deposit into any new or existing account with a bitcoin transaction directly, but it's a somewhat odd process at the moment. See this page if you want to read more.) You can also specify more than one post, and netvend will create multiple, sequential posts. This is helpful for uploading large amounts of data, or uploading many different sets of data at once. In this case, it will still return only one post_id, and the posts will all have sequential ids. So, if you post 10 posts, and get a post_id of 400, you'd know that your posts span the post_ids 400-410. So let's start another agent, then send a tip from our first agent to fund it: new_agent = netvend.Agent("my super secret seed", seed=True) new_address = new_agent.get_address() #netvend stores its credit in uSats. This tip transfers 1 satoshi to the new agent. #the third argument can specify a data entry, to be used as a memo. #in this case, we pass 0 to indicate no memo, #but we could just as easily pass 28 to associate it with our earlier post. response = agent.tip(new_address, netvend.convert_value(1, 'satoshi', 'usat'), None) response will now be something like: {'history_id': 3972, 'command_result': 7, 'success': 1, 'charged': 5000} In this case, command_result indicates the tip_id of the new tip. Our new agent now has full access to the server, until its credit runs out. Like the post command, the tip command can also be used to send several tips at once. If any of the three arguments are lists, netvend will process multiple tips at once. For arguments that aren't lists, the argument will be used for all the tips processed. So if I used agent.tip(addr2, addr3, some_value, some_post_id), three tips would be sent, with identical value and post_ids, but to three different addresses. We could have specified, say, a 3-length list of post_ids as well, if we wanted. Again, netvend will return the tip_id of the first tip, and all other tips processed will have sequential tip_ids. The third command is query. This exposes all of the server's databases to any valid SQL select query. For example, we can look up the 10 highest tips on netvend: #get the sender, recipient, value, and referenced post_id #from the highest 10 tips in netvend's history: query = """ SELECT from_address, to_address, value, post_id FROM tips WHERE 1 ORDER BY value DESC LIMIT 10 """ #we can also set the max query fee. #This call isn't necessary unless your query is more complex or returns a lot of data; #most queries cost less than 2000 uSat, and the default limit is 3000. #agent.set_max_query_fee(3000) #execute the query response = agent.query(query) #get the returned rows from the server's response rows = response'command_result''rows' Like the first two commands, query returns the same variables: charged, history_id, success and command_result. However, command_result is now its own dictionary: * success indicates the success of the SQL query itself, whereas the outside success indicates the command success. If a query command costs too much, the inner success variable will be false, and the outside success variable will be true. * rows contains all rows returned by the SQL query. * num_rows is, as you might guess, the number of rows returned by the query. The query command is very powerful, as SQL SELECT queries are great for analysing, sorting, and combing through data. Any valid SQL SELECT query works. See the netvend database structure to see how to access different tables, but for now just note that you (and all agents with credit) have full access to tip and post data, account balances, and the overall history of netvend. The last command is withdraw, and is simple enough to use: response = agent.withdraw(amount) Again, amount is in uSats. Note that withdrawing very small amounts will deduct funds from your agent, but the server may be unable to actually send the transaction. Netvend will wait until your total requested withdrawals is larger than 1 mBTC, before sending the refund. The refund will go to the same Bitcoin address as agent.get_address, and is therefore controlled by the same seed or private key your agent is. If you have any questions or feedback, don't hesitate to contact me! I'll be happy to fund your account for any project you want to try out. I'll respond to comments here, as well as emails sent to syriven at gmail dot com.